home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / biz / demo / origins.lzh / ARexx / ARexxFuncs.txt next >
Text File  |  1992-09-08  |  30KB  |  858 lines
  1.                           Origins ARexx Functions
  2.                         ©1992 by The Puzzle Factory
  3.  
  4. This documentation is intended to illustrate the ARexx interface to  Origins.
  5. It  is  not  intended  to explain how to use Origins or ARexx, or how various
  6. functions operate.  Please see the Origins or  ARexx documentation  for  more
  7. information.
  8.  
  9. The accompanying ARexx program, ATest.rexx, will help you to  understand  how
  10. these  functions  are to be used.  Make sure that you change the arguments to
  11. the functions to match records in YOUR database  before  trying  to  use  the
  12. test program or the functions.
  13.  
  14. The following symbolic arguments are used in this documention:
  15.  
  16.   NUM     = A cardinal number
  17.   CNUM    = Person Record number of a Child
  18.   FNUM    = Person Record number of a Father
  19.   MNUM    = Person Record number of a Mother
  20.   HNUM    = Person Record number of a Husband
  21.   WNUM    = Person Record number of a Wife
  22.   SNUM    = Person Record number of a Spouse
  23.   PNUM    = Person Record number
  24.   ONUM    = Ordinance Record number
  25.   MARNUM  = Marriage Record number
  26.   SNAME   = Surname (Last name)
  27.   GNAME   = Given name (First name possibly plus middle name(s))
  28.   DATE    = A string taking two possible forms.  Either the more common
  29.             'dd mmm yyyy' or the form 'c.yyyy'.
  30.   YEAR    = A numeric string indicating a year, i.e. '1973'.
  31.   CITY    = The name of a city.
  32.   STATE   = The name of a state.  Alternately, the postal abbreviation,
  33.             i.e. 'OR'.
  34.   COUNTRY = The name of a country.  Alternately, the international
  35.             abbreviation, i.e. 'USA'.
  36.   CODE    = A numeric string from 0 to 65535.  The meaning of this code
  37.             is entirely up to you.  The value of 0 is a null code.
  38.   GENDER  = The character 'M' for male, or 'F' for female.
  39.   (args)  = The argument list for a function.  '|' is used as an OR symbol
  40.             meaning this function may use this argument list OR that
  41.             argument list.  All arguments MUST be supplied to all functions
  42.             unless otherwise noted.  If an argument is unknown, the null
  43.             string "''" must be used.
  44.   'STR'   = A literal string.
  45.   {arg}   = This is used when several strings are to be combined into
  46.             one argument.
  47.   [arg]   = This is used when an argument is optional.
  48.  
  49. In the examples, ">>>" will be used to show console output.
  50. -----------------------------------------------------------------------------
  51. Origins ARexx Functions:
  52. ========================
  53. GENADDMARRIAGE(MARNUM,HNUM,WNUM,CODE,DATE,CITY,COUNTY,STATE,COUNTRY,COMMENT)
  54. GENADDORDINANCE(ONUM,PNUM,BAPTISM,CONFIRM,SPOUSE1,SPOUSE2,SPOUSE3,
  55.                 ARRIVED,ARRDATE,OCCUPATION)
  56. GENADDPERSON(PNUM,FNUM,MNUM,SNAME,GNAME,GENDER,CODE,
  57.              BIRTHDATE,{BIRTHCITY,BIRTHCOUNTY,BIRTHSTATE,BIRTHCOUNTRY},
  58.              DEATHDATE,{DEATHCITY,DEATHCOUNTY,DEATHSTATE,DEATHCOUNTRY},
  59.              BURIALDATE,{BURIALCITY,BURIALCOUNTY,BURIALSTATE,BURIALCOUNTRY})
  60. GENAPPENDRECORDS('PERSON',NUM) | ('ORDINANCE',NUM) | ('MARRIAGE',NUM)
  61. GENCONVERTSOUNDEX(SNAME)
  62. GENCREATEINDEX('PC') | ('MARRIAGE')
  63. GENFINDCHILDREN(FNUM,MNUM)
  64. GENFINDMARRIAGE(MNUM) | ('SEARCH') | ('NEXT') | (HNUM,WNUM)
  65. GENFINDORDINANCE(ONUM) | ('SEARCH') | ('NEXT')
  66. GENFINDPARENTS(CNUM)
  67. GENFINDPERSON(PNUM) | ('SEARCH') | ('NEXT')
  68. GENGETNUMBER('PERSON') | ('ORDINANCE') | ('MARRIAGE') [ACTIVE]
  69. GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)
  70. -----------------------------------------------------------------------------
  71. GENADDMARRIAGE(MARNUM,HNUM,WNUM,CODE,DATE,CITY,COUNTY,STATE,COUNTRY,COMMENT)
  72.  
  73. Arg1=MARNUM:      Type=Numeric, Val = Unsigned 1-PersRecNum
  74. Arg2=HNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  75. Arg3=WNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  76. Arg4=CODE:        Type=Numeric, Val=Unsigned 0-65535
  77. Arg5=DATE:        Type=Alphanumeric, Len=12 chars including NULL.
  78. Arg6=CITY:        Type=Alphanumeric, Len=20 chars including NULL.
  79. Arg7=COUNTY:      Type=Alphanumeric, Len=20 chars including NULL.
  80. Arg8=STATE:       Type=Alphanumeric, Len=20 chars including NULL.
  81. Arg9=COUNTRY:     Type=Alphanumeric, Len=20 chars including NULL.
  82. Arg10=COMMENT:    Type=Alphanumeric, Len=50 chars including NULL.
  83.  
  84. If MARNUM = 0, attempts to add a new ordinance record to the current
  85. database.  If MARNUM = 0, HNUM and WNUM must point to a valid Person records,
  86. or this function will return a bad argument error.  You may want to check if
  87. this record already exists before you add a new one.
  88.  
  89. If MARNUM <> 0, attempts to update an existing record.  If MARNUM <> 0, HNUM
  90. and WNUM must be 0, or this function will return a bad argument error.
  91.  
  92. Note: Except as noted above, all arguments except are optional and may be
  93. null.  If any string argument is null, it will clear the corresponding field
  94. in the record.
  95.  
  96. EXAMPLE:
  97.     /* Attempt to add new ordinance record to database. */
  98.     Call GENADDMARRIAGE(0,5,6,14,'01 Jun 1946','Topeka','','Kansas','USA',,
  99.                    'The weather was absolutely perfect for a June wedding')
  100.     Say Result
  101.     >>> 'Created record 53'
  102.  
  103. RETURNS:
  104.     If successful and this was a new record:
  105.        Result1=RC_OK
  106.        Result2='Created record %ld' where %ld is the new record number
  107.     If successful and this was an existing record:
  108.        Result2='Updated record %ld' where %ld is the old record number
  109.        Fills in these marriage record fields:
  110.        mar_Husband = HNUM
  111.        mar_Wife    = WNUM
  112.        mar_Code    = CODE
  113.        mar_Date    = DATE
  114.        mar_City    = CITY
  115.        mar_County  = COUNTY
  116.        mar_State   = STATE
  117.        mar_Country = COUNTRY
  118.        mar_Comment = COMMENT
  119.  
  120.     If improper, or the wrong number of arguments:
  121.        Result1=RC_WARN
  122.        Result2=NULL
  123.        GEN.LASTERROR='100: Bad arguments'
  124.     If either MARNUM, HNUM or WNUM record number is out of range:
  125.        Result1=RC_WARN
  126.        Result2=NULL
  127.        GEN.LASTERROR='101: Out of range'
  128.     If either MANUM, HNUM or WNUM person records do not exist:
  129.        Result1=RC_WARN
  130.        Result2=NULL
  131.        GEN.LASTERROR='103: No record'
  132.     If either MARNUM, HNUM or WNUM person records could not be read:
  133.        Result1=RC_FATAL
  134.        Result2=NULL
  135.        GEN.LASTERROR='105: Read error'
  136.     If this marriage record could not be written:
  137.        Result1=RC_FATAL
  138.        Result2=NULL
  139.        GEN.LASTERROR='106: Write error'
  140. -----------------------------------------------------------------------------
  141. GENADDORDINANCE(ONUM,PNUM,BAPTISM,CONFIRM,SPOUSE1,SPOUSE2,SPOUSE3,
  142.                 ARRIVED,ARRDATE,OCCUPATION)
  143.  
  144. Arg1=ONUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  145. Arg2=PNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  146. Arg3=BAPTISM:     Type=Alphanumeric, Len=50 chars including NULL.
  147. Arg4=COMFIRM:     Type=Alphanumeric, Len=50 chars including NULL.
  148. Arg5=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  149. Arg6=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  150. Arg7=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  151. Arg8=ARRIVED:     Type=Alphanumeric, Len=50 chars including NULL.
  152. Arg9=ARRDATE:     Type=Alphanumeric, Len=12 chars including NULL.
  153. Arg10=OCCUPATION: Type=Alphanumeric, Len=50 chars including NULL.
  154.  
  155. If ONUM = 0, attempts to add a new ordinance record to the current database.
  156. If ONUM = 0, PNUM must point to a valid Person record, or this function will
  157. return a bad argument error.  You may want to check if this record already
  158. exists before you add a new one.
  159.  
  160. If ONUM <> 0, attempts to update an existing record.  If ONUM <> 0, PNUM must
  161. be 0, or this function will return a bad argument error.
  162.  
  163. Note: Except as noted above, all arguments except are optional and may be
  164. null.  If any string argument is null, it will clear the corresponding field
  165. in the record.
  166.  
  167. Note: If you provide values for SNUM and the records do not exist, the
  168. function will fail, even if the other arguments are correct.  If the values
  169. for SNUM are null, the fields will be cleared!
  170.  
  171. EXAMPLE:
  172.     /* Attempt to add new ordinance record to database. */
  173.     Call GENADDORDINANCE(0,165,'Down by the riverside',,
  174.                       'Our Lady of Perpertual Responsibility',49,2,0,,
  175.                       'Steamship "Hosannah", stearage class','23 Sep 1903',,
  176.                       'Part-time manure salesman')
  177.     Say Result
  178.     >>> 'Created record 147'
  179.  
  180. RETURNS:
  181.     If successful and this was a new record:
  182.        Result1=RC_OK
  183.        Result2='Created record %ld' where %ld is the new record number
  184.        Fills in these ordinance record fields:
  185.        ord_Link       = PNUM
  186.        ord_Baptism    = BAPTISM
  187.        ord_Confirm    = CONFIRM
  188.        ord_Spouse1    = SPOUSE1
  189.        ord_Spouse2    = SPOUSE2
  190.        ord_Spouse3    = SPOUSE3
  191.        ord_Arrived    = ARRIVED
  192.        ord_ArrDate    = ARRDATE
  193.        ord_Occupation = OCCUPATION
  194.  
  195.     If successful and this was an existing record:
  196.        Result1=RC_OK
  197.        Result2='Updated record %ld' where %ld is the old record number
  198.        Fills in these ordinance record fields:
  199.        ord_Baptism    = BAPTISM
  200.        ord_Confirm    = CONFIRM
  201.        ord_Spouse1    = SPOUSE1
  202.        ord_Spouse2    = SPOUSE2
  203.        ord_Spouse3    = SPOUSE3
  204.        ord_Arrived    = ARRIVED
  205.        ord_ArrDate    = ARRDATE
  206.        ord_Occupation = OCCUPATION
  207.  
  208.     If improper, or the wrong number of arguments:
  209.        Result1=RC_WARN
  210.        Result2=NULL
  211.        GEN.LASTERROR='100: Bad arguments'
  212.     If either ONUM or PNUM record number is out of range:
  213.        Result1=RC_WARN
  214.        Result2=NULL
  215.        GEN.LASTERROR='101: Out of range'
  216.     If either ONUM or PNUM person records do not exist:
  217.        Result1=RC_WARN
  218.        Result2=NULL
  219.        GEN.LASTERROR='103: No record'
  220.     If either ONUM or PNUM person records could not be read:
  221.        Result1=RC_FATAL
  222.        Result2=NULL
  223.        GEN.LASTERROR='105: Read error'
  224.     If this ordinance record could not be written:
  225.        Result1=RC_FATAL
  226.        Result2=NULL
  227.        GEN.LASTERROR='106: Write error'
  228. -----------------------------------------------------------------------------
  229. GENADDPERSON(PNUM,FNUM,MNUM,SNAME,GNAME,GENDER,CODE,
  230.              BIRTHDATE,{BIRTHCITY,BIRTHCOUNTY,BIRTHSTATE,BIRTHCOUNTRY},
  231.              DEATHDATE,{DEATHCITY,DEATHCOUNTY,DEATHSTATE,DEATHCOUNTRY},
  232.              BURIALDATE,{BURIALCITY,BURIALCOUNTY,BURIALSTATE,BURIALCOUNTRY})
  233.  
  234. Arg1=PNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  235. Arg2=FNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  236. Arg3=MNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
  237. Arg4=SNAME:       Type=Alphanumeric, Len=20 chars including NULL.
  238. Arg5=GNAME:       Type=Alphanumeric, Len=32 chars including NULL.
  239. Arg6=GENDER:      Type=Char, Val = M or F
  240. Arg7=CODE:        Type=Numeric, Val=Unsigned 0-65535
  241. Arg8=BIRTHDATE:   Type=Alphanumeric, Len=12 chars including NULL.
  242. Arg9=BIRTHPLACE:  Type=Combined Alphanumeric, Len=77 chars including NULL.
  243. Arg10=DEATHDATE:  Type=Alphanumeric, Len=12 chars including NULL.
  244. Arg11=DEATHPLACE: Type=Combined Alphanumeric, Len=77 chars including NULL.
  245. Arg12=BURIALDATE: Type=Alphanumeric, Len=12 chars including NULL.
  246. Arg13=BURIALPLACE:Type=Combined Alphanumeric, Len=77 chars including NULL.
  247.  
  248. If PNUM = 0, attempts to add a new Person to the current database.
  249. You may want to check if this person already exists before you add a new
  250. record.
  251.  
  252. If PNUM <> 0, attempts to update an existing record.
  253.  
  254. Note: All arguments except for SNAME and GENDER are optional and may be
  255. null.  SNAME and GENDER are required!
  256.  
  257. Note: If any string argument, or any part of a combined string argument
  258. is null, it will clear the corresponding field in the record.
  259.  
  260. Note: DO NOT provide a value for FNUM or MNUM unless you know that their
  261. records exist.  If you provide these values and the records do not exist,
  262. the function will fail, even if the other arguments are correct.
  263.  
  264. EXAMPLE:
  265.     /* Attempt to add new person to database.  Parents records are unknown,
  266.        and there death and burial information is also unknown at this time. */
  267.     Call GENADDPERSON(0,0,0,'Squirrel','Rocket J.','M',0,,
  268.                       'c.1968','Frostbite Falls,,MN,USA','','','','')
  269.     Say Result
  270.     >>> 'Created record 126'
  271.  
  272. RETURNS:
  273.     If successful and this was a new record:
  274.        Result1=RC_OK
  275.        Result2='Created record %ld' where %ld is the new record number
  276.     If successful and this was an existing record:
  277.        Result2='Updated record %ld' where %ld is the old record number
  278.        Fills in these person record fields:
  279.        per_Father        = FNUM
  280.        per_Mother        = MNUM
  281.        per_LastName      = SNAME
  282.        per_FirstNames    = GNAME
  283.        per_Sex           = GENDER
  284.        per_Code          = CODE
  285.        per_BirthDate     = BIRTHDATE
  286.        per_BirthCity     = BIRTHCITY
  287.        per_BirthCounty   = BIRTHCOUNTY
  288.        per_BirthState    = BIRTHSTATE
  289.        per_BirthCountry  = BIRTHCOUNTRY
  290.        per_DeathDate     = DEATHDATE
  291.        per_DeathCity     = DEATHCITY
  292.        per_DeathCounty   = DEATHCOUNTY
  293.        per_DeathState    = DEATHSTATE
  294.        per_DeathCountry  = DEATHCOUNTRY
  295.        per_BurialDate    = BURIALDATE
  296.        per_BurialCity    = BURIALCITY
  297.        per_BurialCounty  = BURIALCOUNTY
  298.        per_BurialState   = BURIALSTATE
  299.        per_BurialCountry = BURIALCOUNTRY
  300.  
  301.     If improper, or the wrong number of arguments:
  302.        Result1=RC_WARN
  303.        Result2=NULL
  304.        GEN.LASTERROR='100: Bad arguments'
  305.     If either PNUM, FNUM or MNUM person record number is out of range:
  306.        Result1=RC_WARN
  307.        Result2=NULL
  308.        GEN.LASTERROR='101: Out of range'
  309.     If either PNUM, FNUM or MNUM person records do not exist:
  310.        Result1=RC_WARN
  311.        Result2=NULL
  312.        GEN.LASTERROR='103: No record'
  313.     If either PNUM, FNUM or MNUM person records could not be read:
  314.        Result1=RC_FATAL
  315.        Result2=NULL
  316.        GEN.LASTERROR='105: Read error'
  317.     If this person record could not be written:
  318.        Result1=RC_FATAL
  319.        Result2=NULL
  320.        GEN.LASTERROR='106: Write error'
  321. -----------------------------------------------------------------------------
  322. GENAPPENDRECORDS('PERSON',NUM) | ('ORDINANCE',NUM) | ('MARRIAGE',NUM)
  323.  
  324. Arg1=PERSON:    Type=Boolean keyword
  325. Arg1=ORDINANCE: Type=Boolean keyword
  326. Arg1=MARRIAGE:  Type=Boolean keyword
  327. Arg2=NUM:       Type=Numeric, Val = Signed 1-(2^31-xxxRecNum)
  328.  
  329. Attempts to add blank Person, Ordinance, or Marriage records.  This number is
  330. desired number of records to add, not total number of records.  Thus, if a
  331. persfile had 100 records, and you called this function with the argument of
  332. NUM=130, you would have 230 person records total.
  333.  
  334. EXAMPLE:
  335.     /* Add 100 blank person records */
  336.     Call GENAPPENDRECORDS(PERSON,100)
  337.     Say RESULT
  338.     >>> '200 records'
  339.  
  340. RETURNS:
  341.     If successful:
  342.        Result1=RC_OK
  343.        Result2='%ld records' where %ld is the new total number of the
  344.                             requested type of records.
  345.  
  346.     If improper, or the wrong number of arguments:
  347.        Result1=RC_WARN
  348.        Result2=NULL
  349.        GEN.LASTERROR='100: Bad arguments'
  350.     If any record could not be written:
  351.        Result1=RC_FATAL
  352.        Result2=NULL
  353.        GEN.LASTERROR='106: Write error'
  354.     If there was a seek error in the file:
  355.        Result1=RC_FATAL
  356.        Result2=NULL
  357.        GEN.LASTERROR='108: Seek error'
  358. -----------------------------------------------------------------------------
  359.  
  360. GENCONVERTSOUNDEX(SNAME)
  361.  
  362. Arg1=SNAME:   Type=Alphanumeric, Len=20 chars including NULL.
  363.  
  364. Attempts to convert SNAME to a soundex code.
  365.  
  366. EXAMPLE:
  367.     LASTNAME='Smith'
  368.     Call GENCONVERTSOUNDEX(LASTNAME)
  369.     Say "The Soundex representation of" LASTNAME "is" RESULT
  370.     >>> The Soundex representation of Smith is S530
  371.  
  372. RETURNS:
  373.     If successful:
  374.        Result1=RC_OK
  375.        Result2=The converted surname
  376.  
  377.     If improper, or the wrong number of arguments:
  378.        Result1=RC_WARN
  379.        Result2=NULL
  380.        GEN.LASTERROR='100: Bad arguments'
  381. -----------------------------------------------------------------------------
  382. GENCREATEINDEX('PC') | ('MARRIAGE')
  383.  
  384. Arg1=PC:        Type=Boolean keyword
  385. Arg1=MARRIAGE:  Type=Boolean keyword
  386.  
  387. Attempts to create the Parent/Child or Marriage index.
  388.  
  389. EXAMPLES:
  390.     /* Index existing parent/child relationships */
  391.     Call GENCREATEINDEX('PC')
  392.     Say RESULT
  393.     >>> 'Created PC index'
  394.  
  395.     /* Index existing marriage relationships */
  396.     Call GENCREATEINDEX('MARRIAGE')
  397.     Say RESULT
  398.     >>> 'Created marriage index'
  399.  
  400. RETURNS:
  401.     If successful:
  402.        Result1=RC_OK
  403.        Result2='Created PC index' if PC argument
  404.        Result2='Created marriage index' if MARRIAGE argument
  405.  
  406.     If improper, or the wrong number of arguments:
  407.        Result1=RC_WARN
  408.        Result2=NULL
  409.        GEN.LASTERROR='100: Bad arguments'
  410.  
  411.     If index file could not be written:
  412.        Result1=RC_FATAL
  413.        Result2=NULL
  414.        GEN.LASTERROR='106: Write error'
  415.  
  416.     If index file could not be opened:
  417.        Result1=RC_FATAL
  418.        Result2=NULL
  419.        GEN.LASTERROR='107: Open error'
  420.  
  421.     If could not allocate memory for index file:
  422.        Result1=RC_FATAL
  423.        Result2=NULL
  424.        GEN.LASTERROR='109: No memory'
  425. -----------------------------------------------------------------------------
  426. GENFINDCHILDREN(FNUM,MNUM)
  427.  
  428. Arg1=FNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  429. Arg2=MNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  430.  
  431. Given Person record numbers of both partners, finds only children common to
  432. both, and returns list sorted by birthdate.  Note that there may not be any
  433. children to find.
  434.  
  435. EXAMPLES:
  436.     Call GENFINDCHILDREN(58,61)
  437.     If value(word(Result,1))>0 then do  /* If any children */
  438.         Say Result
  439.         >>> '3 children found'
  440.         do i=1 to (word(Result,1))
  441.         Say "Child"i" is" CHILD.i
  442.         end i
  443.     end
  444.  
  445. RETURNS:
  446.     If successful:
  447.        Result1=RC_OK
  448.        Result2='%d children found' where %d is the number of children found
  449.        Fills in these ARexx variables:
  450.        CHILD.%d where %d is the person record number
  451.  
  452.     If improper, or the wrong number of arguments:
  453.        Result1=RC_WARN
  454.        Result2=NULL
  455.        GEN.LASTERROR='100: Bad arguments'
  456.     If either person record number is out of range:
  457.        Result1=RC_WARN
  458.        Result2=NULL
  459.        GEN.LASTERROR='101: Out of range'
  460.     If the parent/child index is unavailable:
  461.        Result1=RC_ERROR
  462.        Result2=NULL
  463.        GEN.LASTERROR='104: No index'
  464.     If no child record exists:
  465.        Result1=RC_WARN
  466.        Result2=NULL
  467.        GEN.LASTERROR='103: No record'
  468.     If person records could not be read:
  469.        Result1=RC_FATAL
  470.        Result2=NULL
  471.        GEN.LASTERROR='105: Read error'
  472. -----------------------------------------------------------------------------
  473. GENFINDMARRIAGE (MARNUM) | ('SEARCH') | ('NEXT') | (HNUM,WNUM)
  474.  
  475. Arg1=MARNUM:  Type=Numeric, Val = Unsigned 1-MarrRecNum
  476. Arg1=SEARCH:  Type=Boolean keyword
  477. Arg1=NEXT:    Type=Boolean keyword
  478.  
  479. Arg1=HNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  480. Arg2=WNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  481.  
  482. If given one number, returns data on that marriage.
  483.  
  484. If given two numbers, attempts to translate the person numbers into a
  485. marriage number.  If successful, returns data on that marriage.  This
  486. form has less overhead than a search.
  487.  
  488. If given the SEARCH flag, attempts to locate the first record that matches
  489. the described person.  If successful, attempts to translate the person number
  490. into a marriage number.  If successful, and if there was only one marriage,
  491. returns data on that marriage.  If successful, and there were multiple
  492. marriages, returns a list of spouses.  Uses current settings of search
  493. buffers.
  494.  
  495. If given the NEXT flag, attempts to locate the next record that matches the
  496. described person.  If successful, attempts to translate the person number
  497. into a marriage number.  If successful, and if there was only one marriage,
  498. returns data on that marriage.  If successful, and there were multiple
  499. marriages, returns a list of spouses.  Uses current settings of search
  500. buffers.
  501.  
  502. EXAMPLES:
  503.     Call GENFINDMARRIAGE('SEARCH')
  504.     If Result = 'Found marriage' then do     /* If a single marriage */
  505.        Say Result
  506.        >>> 'Found marriage'
  507.        Say "Record #:" MARRIAGE.RECORD
  508.        Say "Husband: " MARRIAGE.HUSBAND
  509.        ...
  510.        Say "Comment: " MARRIAGE.COMMENT
  511.     end
  512.  
  513.     If DataType(word(Result,1))=NUM then do  /* If multiple marriages */
  514.         Say Result
  515.         >>> '2 marriages found'
  516.         do i=1 to (word(Result,1))
  517.         Say "Spouse"i" is" MARRIAGE.SPOUSE.i
  518.         end i
  519.     end
  520.  
  521.     /* Find the next marriage that matches the previously described person */
  522.     Call GENFINDMARRIAGE('NEXT')
  523.  
  524.     /* Find marrigae record 27 */
  525.     Call GENFINDMARRIAGE(27)
  526.  
  527.     /* Find the marriage record for these two people  */
  528.     /* Will not find multiple marriages - only single */
  529.     Call GENFINDMARRIAGE2(102,103)
  530.  
  531.  
  532. RETURNS:
  533.     If successful and a single marriage:
  534.        Result1=RC_OK
  535.        Result2='Found marriage'
  536.        Fills in these ARexx variables:
  537.        MARRIAGE.RECORD  = mar_Record
  538.        MARRIAGE.HUSBAND = mar_Husband
  539.        MARRIAGE.WIFE    = mar_Wife
  540.        MARRIAGE.CODE    = mar_Code
  541.        MARRIAGE.DATE    = mar_Date
  542.        MARRIAGE.CITY    = mar_City
  543.        MARRIAGE.COUNTY  = mar_County
  544.        MARRIAGE.STATE   = mar_State
  545.        MARRIAGE.COUNTRY = mar_Country
  546.        MARRIAGE.COMMENT = mar_Comment
  547.  
  548.     If successful and multiple marriages:
  549.        Result1=RC_OK
  550.        Result2='%d marriages found' where %d is the number of marriages found
  551.        Fills in these ARexx variables:
  552.        MARRIAGE.SPOUSE.%d where %d is the person record number
  553.  
  554.     If improper, or the wrong number of arguments:
  555.        Result1=RC_WARN
  556.        Result2=NULL
  557.        GEN.LASTERROR='100: Bad arguments'
  558.     If the person record number is out of range:
  559.        Result1=RC_WARN
  560.        Result2=NULL
  561.        GEN.LASTERROR='101: Out of range'
  562.     If search failed:
  563.        Result1=RC_ERROR
  564.        Result2=NULL
  565.        GEN.LASTERROR='102: Search failed'
  566.     If the marriage record does not exist:
  567.        Result1=RC_WARN
  568.        Result2=NULL
  569.        GEN.LASTERROR='103: No record'
  570.     If the marriage index is unavailable:
  571.        Result1=RC_ERROR
  572.        Result2=NULL
  573.        GEN.LASTERROR='104: No index'
  574.     If record could not be read:
  575.        Result1=RC_FATAL
  576.        Result2=NULL
  577.        GEN.LASTERROR='105: Read error'
  578. -----------------------------------------------------------------------------
  579. GENFINDORDINANCE (ONUM) | ('SEARCH') | ('NEXT')
  580.  
  581. Arg1=ONUM:    Type=Numeric, Val = Unsigned 1-OrdRecNum
  582. Arg1=SEARCH:  Type=Boolean keyword
  583. Arg1=NEXT:    Type=Boolean keyword
  584.  
  585. If given a number, returns data on that ordinance.
  586.  
  587. If given the SEARCH flag, attempts to locate the first record that matches
  588. the described person.  If successful, attempts to translate the person number
  589. into an ordinance number.  If successful, returns data on that ordinance.
  590. Uses current settings of search buffers.
  591.  
  592. If given the NEXT flag, attempts to locate the next record that matches the
  593. described person.  If successful, attempts to translate the person number
  594. into an ordinance number.  If successful, returns data on that ordinance.
  595. Uses current settings of search buffers.
  596.  
  597. EXAMPLE:
  598.     /* Find the first record that matches the previously described person */
  599.     Call GENFINDORDINANCE('SEARCH')
  600.     Say Result
  601.     >>> 'Found ordinance'
  602.  
  603.     Say ORDINANCE.RECORD
  604.     Say ORDINANCE.BAPTISM
  605.         ...
  606.     Say ORDINANCE.OCCUPATION
  607.  
  608.     /* Find the next record that matches the previously described person */
  609.     Call GENFINDORDINANCE('NEXT')
  610.     Say Result
  611.     >>> 'Found ordinance'
  612.  
  613.     /* Find ordinance record 27 */
  614.     Call GENFINDORDINANCE(27)
  615.     Say Result
  616.     >>> 'Found ordinance'
  617.  
  618. RETURNS:
  619.     If successful:
  620.        Result1=RC_OK
  621.        Result2='Found ordinance'
  622.        Fills in these ARexx variables:
  623.        ORDINANCE.RECORD       = ord_RecNo
  624.        ORDINANCE.BAPTISM      = ord_Baptism
  625.        ORDINANCE.CONFIRMATION = ord_Confirm
  626.        ORDINANCE.SPOUSE1      = ord_Spouse1
  627.        ORDINANCE.SPOUSE2      = ord_Spouse2
  628.        ORDINANCE.SPOUSE3      = ord_Spouse3
  629.        ORDINANCE.ARRIVED      = ord_Arrived
  630.        ORDINANCE.ARRDATE      = ord_ArrDate
  631.        ORDINANCE.OCCUPATION   = ord_Occupation
  632.  
  633.     If improper, or the wrong number of arguments:
  634.        Result1=RC_WARN
  635.        Result2=NULL
  636.        GEN.LASTERROR='100: Bad arguments'
  637.     If the person record number is out of range:
  638.        Result1=RC_WARN
  639.        Result2=NULL
  640.        GEN.LASTERROR='101: Out of range'
  641.     If search failed:
  642.        Result1=RC_ERROR
  643.        Result2=NULL
  644.        GEN.LASTERROR='102: Search failed'
  645.     If the ordinance record does not exist:
  646.        Result1=RC_WARN
  647.        Result2=NULL
  648.        GEN.LASTERROR='103: No record'
  649.     If record could not be read:
  650.        Result1=RC_FATAL
  651.        Result2=NULL
  652.        GEN.LASTERROR='105: Read error'
  653. -----------------------------------------------------------------------------
  654. GENFINDPARENTS(CNUM)
  655.  
  656. Arg1=CNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  657.  
  658. Given Person record number of a Child, returns both parents.  If there is
  659. only one parent, the other variable will be cleared.  Note that there may not
  660. be any parents to find.
  661.  
  662. EXAMPLES:
  663.     Call GENFINDPARENTS(132)
  664.     Say "Father is" FATHER
  665.     Say "Mother is" MOTHER
  666.  
  667. RETURNS:
  668.     If successful:
  669.        Result1=RC_OK
  670.        Result2='Found parents'
  671.        Fills in these ARexx variables:
  672.        FATHER = Father
  673.        MOTHER = Mother
  674.  
  675.     If improper, or the wrong number of arguments:
  676.        Result1=RC_WARN
  677.        Result2=NULL
  678.        GEN.LASTERROR='100: Bad arguments'
  679.     If person record number is out of range:
  680.        Result1=RC_WARN
  681.        Result2=NULL
  682.        GEN.LASTERROR='101: Out of range'
  683.     If no parent records exist:
  684.        Result1=RC_WARN
  685.        Result2=NULL
  686.        GEN.LASTERROR='103: No record'
  687.     If the parent/child index is unavailable:
  688.        Result1=RC_ERROR
  689.        Result2=NULL
  690.        GEN.LASTERROR='104: No index'
  691.     If record could not be read:
  692.        Result1=RC_FATAL
  693.        Result2=NULL
  694.        GEN.LASTERROR='105: Read error'
  695. -----------------------------------------------------------------------------
  696. GENFINDPERSON(PNUM) | ('SEARCH') | ('NEXT')
  697.  
  698. Arg1=PNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
  699. Arg1=SEARCH:  Type=Boolean keyword
  700. Arg1=NEXT:    Type=Boolean keyword
  701.  
  702. If given a number, returns data on that person.
  703.  
  704. If given the SEARCH flag, attempts to locate the first record that matches
  705. the described person.  If successful, returns data on that person.  Uses
  706. current settings of search buffers.
  707.  
  708. If given the NEXT flag, attempts to locate the next record that matches the
  709. described person.  If successful, returns data on that person.  Uses current
  710. settings of search buffers.
  711.  
  712. EXAMPLE:
  713.     /* Find the 1st record that matches the previously described person */
  714.     Call GENFINDPERSON('SEARCH')
  715.     Say Result
  716.     >>> 'Found person'
  717.  
  718.     Say PERSON.RECORD
  719.     Say PERSON.FATHER
  720.         ...
  721.     Say PERSON.BURIALCOUNTRY
  722.  
  723.     /* Find the next record that matches the previously described person */
  724.     Call GENFINDPERSON('NEXT')
  725.     Say Result
  726.     >>> 'Found person'
  727.  
  728.     /* Find person record 27 */
  729.     Call GENFINDPERSON(27)
  730.     Say Result
  731.     >>> 'Found person'
  732.  
  733. RETURNS:
  734.     If successful:
  735.        Result1=RC_OK
  736.        Result2='Found person'
  737.        Fills in these ARexx variables:
  738.        PERSON.RECORD       = per_RecNo
  739.        PERSON.FATHER       = per_Father
  740.        PERSON.MOTHER       = per_Mother
  741.        PERSON.SURNAME      = per_LastName
  742.        PERSON.GIVNAME      = per_FirstNames
  743.        PERSON.SEX          = per_Sex
  744.        PERSON.CODE         = per_Code
  745.        PERSON.BIRTHDATE    = per_BirthDate
  746.        PERSON.BIRTHCITY    = per_BirthCity
  747.        PERSON.BIRTHCOUNTY  = per_BirthCounty
  748.        PERSON.BIRTHSTATE   = per_BirthState
  749.        PERSON.BIRTHCOUNTRY = per_BirthCountry
  750.        PERSON.DEATHDATE    = per_DeathDate
  751.        PERSON.DEATHCITY    = per_DeathCity
  752.        PERSON.DEATHCOUNTY  = per_DeathCounty
  753.        PERSON.DEATHSTATE   = per_DeathState
  754.        PERSON.DEATHCOUNTRY = per_DeathCountry
  755.        PERSON.BURIALDATE   = per_BurialDate
  756.        PERSON.BURIALCITY   = per_BurialCity
  757.        PERSON.BURIALCOUNTY = per_BurialCounty
  758.        PERSON.BURIALSTATE  = per_BurialState
  759.        PERSON.BURIALCOUNTRY= per_BurialCountry
  760.  
  761.     If improper, or the wrong number of arguments:
  762.        Result1=RC_WARN
  763.        Result2=NULL
  764.        GEN.LASTERROR='100: Bad arguments'
  765.     If the person record number is greater than the total size of the
  766.     database, or the returned record is not an active record:
  767.        Result1=RC_WARN
  768.        Result2=NULL
  769.        GEN.LASTERROR='101: Out of range'
  770.     If search failed:
  771.        Result1=RC_ERROR
  772.        Result2=NULL
  773.        GEN.LASTERROR='102: Search failed'
  774.     If record could not be read:
  775.        Result1=RC_FATAL
  776.        Result2=NULL
  777.        GEN.LASTERROR='105: Read error'
  778. -----------------------------------------------------------------------------
  779. GENGETNUMBER('PERSON') | ('ORDINANCE') | ('MARRIAGE') [ACTIVE]
  780.  
  781. Arg1=PERSON:    Type=Boolean keyword
  782. Arg1=ORDINANCE: Type=Boolean keyword
  783. Arg1=MARRIAGE:  Type=Boolean keyword
  784. Arg2=ACTIVE:    Type=Boolean keyword, optional
  785.  
  786. Finds the number of current Person, Ordinance, or Marriage records.  This
  787. number is total records, not active records.  Thus, in a newly created
  788. persfile, there would be 100 records.
  789.  
  790. EXAMPLE:
  791.     /* Find out how many person records currently exist */
  792.     Call GENGETNUMBER(PERSON)
  793.     Say RESULT
  794.     >>> '100 records'
  795.  
  796.     /* Find out how many marriage records currently are in use */
  797.     Call GENGETNUMBER(MARRIAGE,ACTIVE)
  798.     Say RESULT
  799.     >>> '58 records'
  800.  
  801. RETURNS:
  802.     If successful:
  803.        Result1=RC_OK
  804.        Result2='%ld records' where %ld is the number of the requested type
  805.                                of records.
  806.  
  807.     If improper, or the wrong number of arguments:
  808.        Result1=RC_WARN
  809.        Result2=NULL
  810.        GEN.LASTERROR='100: Bad arguments'
  811.     If the 'ACTIVE' argument is used, this function may also return:
  812.        Result1=RC_FATAL
  813.        Result2=NULL
  814.        GEN.LASTERROR='105: Read error'
  815. -----------------------------------------------------------------------------
  816. GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)
  817.  
  818. Arg1=SNAME:   Type=Alphanumeric, Len=20 chars including NULL.
  819. Arg2=GNAME:   Type=Alphanumeric, Len=32 chars including NULL.
  820. Arg3=YEAR:    Type=Numeric, Val=Unsigned 1-9999 (see Origins docs)
  821. Arg4=CITY:    Type=Alphanumeric, Len=20 chars including NULL.
  822. Arg5=COUNTRY: Type=Alphanumeric, Len=20 chars including NULL.
  823. Arg6=CODE:    Type=Numeric, Val=Unsigned 0-65535
  824. Arg7=GENDER:  Type=Char, Val = M or F
  825.  
  826. Sets up the search buffers with the supplied arguments.  All strings may be
  827. partial names.  A null arguments will clear its respective buffer.  All
  828. arguments are required.  This function also clears the LastSearch result.
  829.  
  830. EXAMPLE:
  831.     /* Put the arguments into variables, perhaps from the command line */
  832.     SNAME='Doe';GNAME='John';YEAR=1955;CITY='Toledo';COUNTRY='USA'
  833.     CODE=4;GENDER='M'
  834.     Call GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)
  835.  
  836.     /* or supply the arguments directly */
  837.     Call GENSETSEARCH('Doe','John',1955,'Toledo','USA',4,'M')
  838.     Say Result
  839.     >>> Search buffers set
  840.  
  841.     /* You must supply all arguments to this function,
  842.     but any    string arguments may be partial, or any
  843.     arguments may be set to null as follows */
  844.     Call GENSETSEARCH('Doe','',1955,'Tol','USA','','M')
  845.     Say Result
  846.     >>> Search buffers set
  847.  
  848. RETURNS:
  849.     If successful:
  850.        Result1=RC_OK
  851.        Result2='Search buffers set'
  852.  
  853.     If improper, or the wrong number of arguments:
  854.        Result1=RC_WARN
  855.        Result2=NULL
  856.        GEN.LASTERROR='100: Bad arguments'
  857. -----------------------------------------------------------------------------
  858.